feat(namesys): propagate DNSLink TXT TTL - #1167
Merged
Merged
Conversation
The DNS resolver dropped the TXT record TTL, so a gateway could not set Cache-Control max-age for DNSLink (/ipns/<dnslink-host>) responses, and a recursive name was cached for only its final hop's TTL. - add LookupTXTWithTTLFunc and NewDNSResolverWithTTL; LookupTXTFunc and NewDNSResolver keep their signatures and report an unknown TTL (0) - carry the looked-up TTL into AsyncResult.TTL in the DNS resolver - WithDNSResolver detects a resolver implementing multiformats/go-multiaddr-dns#75 TXTWithTTLResolver and propagates the TTL; add WithDNSResolverWithTTL for a TTL-aware lookup - cap a resolved name's TTL to its shortest hop, so a DNSLink or recursive IPNS name is not cached past its earliest-expiring link Refs #329
lidel
marked this pull request as ready for review
June 3, 2026 17:10
Codecov Report❌ Patch coverage is
@@ Coverage Diff @@
## main #1167 +/- ##
==========================================
- Coverage 63.87% 63.83% -0.04%
==========================================
Files 269 269
Lines 27073 27097 +24
==========================================
+ Hits 17293 17298 +5
- Misses 8072 8083 +11
- Partials 1708 1716 +8
... and 10 files with indirect coverage changes 🚀 New features to boost your workflow:
|
gammazero
approved these changes
Jun 3, 2026
drop the min from negative inputs so a negative TTL is never returned; cover the negative cases in the test table.
gammazero
approved these changes
Jun 7, 2026
This was referenced Jun 7, 2026
WithMaxCacheTTL capped only how long an entry stayed in the resolution cache; the TTL emitted in results (which a gateway turns into Cache-Control max-age) was not capped, and cache hits reported the entry's original TTL for the whole cache window, letting clients hold a result up to twice the intended time. - cap the TTL of fresh results with the same maxCacheTTL bound - report a cache hit's remaining lifetime instead of its original TTL - clamp a negative cap to 0 so it is never emitted
# Conflicts: # CHANGELOG.md # namesys/namesys_cache.go # namesys/namesys_test.go
namesys detects the TTL capability only at runtime, so a signature drift in madns or go-doh-resolver would silently drop DNSLink Cache-Control max-age. The assertion turns that into a compile error.
kubo's offline node passes WithMaxCacheTTL(0) to mean "no cache"; capping the reported TTL to that value dropped Cache-Control max-age for IPNS responses on offline gateways (caught by kubo's TestGateway/IPNS via the Gateway Sharness workflow). A non-positive cap now only disables retention, while a positive cap still bounds both the cache window and the reported TTL.
Gateway behavior is shaped by code outside gateway/: resolution TTLs from namesys become Cache-Control max-age, ipns governs record TTL and validation, and path parses gateway input. A namesys-only change broke kubo's TestGateway/IPNS without triggering this workflow until an unrelated gateway/ commit ran it.
Replaces the pseudo-version pins of the upstream PR branches with the tagged releases. DoH resolvers now report TXT TTLs, which activates DNSLink Cache-Control max-age end to end via WithDNSResolver's auto-detection.
Go's net.Resolver returns only record values, so the OS resolver cannot report TTLs and domains it serves keep a static Cache-Control. Spell that out in WithDNSResolver and gateway.NewDNSResolver godocs, with the catch-all "." DoH entry as the way to cover every domain.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
boxo's DNS resolver discards the TTL of DNSLink TXT records and returns 0. The gateway sets
Cache-Control: max-agefor mutable paths only when the TTL is non-zero, so DNSLink (/ipns/<dnslink-host>) responses go out with no max-age and fall back to a static value, even though the TXT record states exactly how long the mapping is valid (#329). Recursive names made it worse: a name resolved through several records was cached for only its final hop's TTL, ignoring shorter-lived links earlier in the chain.Fix
AsyncResult.TTL/Result.TTL), which the gateway turns intoCache-Control: max-age.WithDNSResolverauto-detects a resolver that implementsmadns.TXTWithTTLResolver;NewDNSResolverWithTTL,WithDNSResolverWithTTL, andLookupTXTWithTTLFunctake a TTL-aware lookup directly. Shipped end to end: go-multiaddr-dns v0.6.0 defines the interface, go-doh-resolver v0.6.0 implements it, both are pinned here, and a compile-time assertion ingatewaymakes a future drift break the build instead of silently dropping TTLs.WithMaxCacheTTLnow also caps the TTL reported in results (making Kubo's documentedIpns.MaxCacheTTLbehavior true in emitted headers), and cache hits report the entry's remaining lifetime instead of its original TTL, so a late hit no longer restarts the full caching period. A cap of 0 still means "no local cache" and leaves the TTL alone (Kubo's offline mode relies on that); the gateway sharness workflow now also watchesnamesys/ipns/pathso a regression there cannot slip through untested again.NewDNSResolverandLookupTXTFunckeep their signatures and report an unknown TTL (0). TTLs flow only for domains resolved through DoH1; everything else keeps today's static behavior. Independent of DoH, two changes apply to all namesys users: theWithMaxCacheTTLcap and remaining-lifetime cache hits.Part of #329. ETag for resolved paths (the issue's other half) is out of scope.
Footnotes
The OS resolver cannot report TTLs: Go's
net.Resolverreturns only record values, andmadns.DefaultResolverwraps it. In Kubo, aDNS.Resolversentry for.routes every lookup through DoH. ↩